package com.joker.demo.core.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.concurrent.TimeUnit;

/**
 * 任务处理器注解
 * 
 * 这个注解用于标记任务处理器，支持类级别和方法级别的任务处理。
 * 当任务执行器扫描到带有此注解的类或方法时，会自动注册为任务处理器。
 * 
 * 使用方式：
 * 1. 类级别：在类上添加@JobHandle注解，类需要实现JobExecutorService接口
 * 2. 方法级别：在方法上添加@JobHandle注解，方法会被注册为任务处理器
 * 
 * 注解属性说明：
 * - value: 任务名称，必须指定，用于标识任务
 * - desc: 任务描述，可选，默认为任务名称
 * - retryCount: 失败重试次数，可选，默认不重试
 * - cron: 定时表达式，可选，不设置则为手动执行
 * - timeout: 超时时间，可选，默认30秒
 * - timeoutUnit: 超时时间单位，可选，默认秒
 * - alarmEmail: 告警邮箱，可选，任务超时时发送告警
 * - init: 初始化方法名，可选，任务执行器启动时调用
 * - destroy: 销毁方法名，可选，任务执行器停止时调用
 *
 * @author feixiang.li
 * @since 2025-07-05
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface JobHandle {

    /**
     * 任务名称
     * 
     * 这是任务的唯一标识符，必须指定。
     * 调度中心会根据这个名称来调用对应的任务处理器。
     * 
     * @return 任务名称
     */
    String value();

    /**
     * 任务描述
     * 
     * 用于描述任务的功能和用途，便于管理和维护。
     * 如果不设置，默认使用任务名称作为描述。
     * 
     * @return 任务描述
     */
    String desc() default "";

    /**
     * 失败重试次数
     * 
     * 当任务执行失败时，会自动重试指定的次数。
     * 设置为0表示不重试，设置为正数表示重试次数。
     * 
     * @return 重试次数
     */
    int retryCount() default 0;

    /**
     * 定时表达式
     * 
     * 用于配置任务的定时执行规则，使用标准的cron表达式格式。
     * 如果不设置，任务只能通过调度中心手动触发执行。
     * 
     * 示例：
     * - "0 0 12 * * ?" 每天中午12点执行
     * - "0 15 10 * * ?" 每天上午10点15分执行
     * - "0 0/30 * * * ?" 每30分钟执行一次
     * 
     * @return cron表达式
     */
    String cron() default "";

    /**
     * 任务超时时间
     * 
     * 任务执行的最大时间限制，超过此时间会触发告警。
     * 注意：超时不会终止任务执行，只会发送告警通知。
     * 
     * @return 超时时间
     */
    int timeout() default 30;

    /**
     * 超时时间单位
     * 
     * 配合timeout属性使用，指定超时时间的单位。
     * 
     * @return 时间单位
     */
    TimeUnit timeoutUnit() default TimeUnit.SECONDS;

    /**
     * 告警邮箱地址
     * 
     * 当任务执行超时或失败时，会向此邮箱发送告警通知。
     * 支持多个邮箱地址，用逗号分隔。
     * 
     * @return 告警邮箱地址
     */
    String alarmEmail() default "";

    /**
     * 初始化方法名
     * 
     * 任务执行器启动时调用的方法名。
     * 该方法应该是一个无参数的公共方法，用于初始化任务相关的资源。
     * 
     * @return 初始化方法名
     */
    String init() default "";

    /**
     * 销毁方法名
     * 
     * 任务执行器停止时调用的方法名。
     * 该方法应该是一个无参数的公共方法，用于清理任务相关的资源。
     * 
     * @return 销毁方法名
     */
    String destroy() default "";
}
